{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "c950beef",
   "metadata": {},
   "source": [
    "# GncOptimizer\n",
    "\n",
    "## Overview\n",
    "\n",
    "The `GncOptimizer` class in GTSAM is designed to perform robust optimization using Graduated Non-Convexity (GNC). This method is particularly useful in scenarios where the optimization problem is affected by outliers. The GNC approach gradually transitions from a convex approximation of the problem to the original non-convex problem, thereby improving robustness and convergence.\n",
    "\n",
    "The `GncOptimizer` leverages a robust cost function $\\rho(e)$, where $e$ is the error term. The goal is to minimize the sum of these robust costs over all measurements:\n",
    "\n",
    "$$\n",
    "\\min_x \\sum_i \\rho(e_i(x))\n",
    "$$\n",
    "\n",
    "In the context of GNC, the robust cost function is gradually transformed from a convex approximation to the original non-convex form. This transformation is controlled by a parameter $\\mu$, which is adjusted during the optimization process:\n",
    "\n",
    "$$\n",
    "\\rho_\\mu(e) = \\frac{1}{\\mu} \\rho(\\mu e)\n",
    "$$\n",
    "\n",
    "As $\\mu$ increases, the function $\\rho_\\mu(e)$ transitions from a convex to a non-convex shape, allowing the optimizer to handle outliers effectively.\n",
    "\n",
    "Key features:\n",
    "\n",
    "- **Robust Optimization**: The GncOptimizer is specifically tailored to handle optimization problems with outliers, using a robust cost function that can mitigate their effects.\n",
    "- **Graduated Non-Convexity**: This technique allows the optimizer to start with a convex problem and gradually transform it into the original non-convex problem, which helps in avoiding local minima.\n",
    "- **Customizable Parameters**: Users can adjust various parameters to control the behavior of the optimizer, such as the type of robust loss function and the parameters governing the GNC process.\n",
    "\n",
    "## Key Methods\n",
    "\n",
    "Please see the base class [NonlinearOptimizer.ipynb](NonlinearOptimizer.ipynb).\n",
    "\n",
    "## Parameters\n",
    "\n",
    "The `GncParams` class defines parameters specific to the GNC optimization algorithm:\n",
    "\n",
    "| Parameter | Type | Default Value | Description |\n",
    "|-----------|------|---------------|-------------|\n",
    "| lossType | GncLossType | TLS | Type of robust loss function (GM = Geman McClure or TLS = Truncated least squares) |\n",
    "| maxIterations | size_t | 100 | Maximum number of iterations |\n",
    "| muStep | double | 1.4 | Multiplicative factor to reduce/increase mu in GNC |\n",
    "| relativeCostTol | double | 1e-5 | Threshold for relative cost change to stop iterating |\n",
    "| weightsTol | double | 1e-4 | Threshold for weights being close to binary to stop iterating (TLS only) |\n",
    "| verbosity | Verbosity enum | SILENT | Verbosity level (options: SILENT, SUMMARY, MU, WEIGHTS, VALUES) |\n",
    "| knownInliers | IndexVector | Empty | Slots in factor graph for measurements known to be inliers |\n",
    "| knownOutliers | IndexVector | Empty | Slots in factor graph for measurements known to be outliers |\n",
    "\n",
    "These parameters complement the standard optimization parameters inherited from `NonlinearOptimizerParams`, which include:\n",
    "\n",
    "- Maximum iterations\n",
    "- Relative and absolute error thresholds\n",
    "- Error function verbosity\n",
    "- Linear solver type\n",
    "\n",
    "## Usage Considerations\n",
    "\n",
    "- **Outlier Rejection**: The `GncOptimizer` is particularly effective in scenarios with significant outlier presence, such as SLAM or bundle adjustment problems.\n",
    "- **Parameter Tuning**: Proper tuning of the GNC parameters is crucial for achieving optimal performance. Users should experiment with different settings to find the best configuration for their specific problem.\n",
    "\n",
    "## Files\n",
    "\n",
    "- [GncOptimizer.h](https://github.com/borglab/gtsam/blob/develop/gtsam/nonlinear/GncOptimizer.h)\n",
    "- [GncParams.h](https://github.com/borglab/gtsam/blob/develop/gtsam/nonlinear/GncParams.h)"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
